Generic Attribute Profile (GATT)

GATT layer manages the service database providing APIs for service registration and attribute declaration.

Services can be registered using bt_gatt_service_register() API which takes the bt_gatt_service struct that provides the list of attributes the service contains. The helper macro BT_GATT_SERVICE() can be used to declare a service.

Attributes can be declared using the bt_gatt_attr struct or using one of the helper macros:

Declares a Primary Service.

Declares a Secondary Service.

Declares a Include Service.

Declares a Characteristic.

Declares a Descriptor.

Declares an Attribute.

Declares a Client Characteristic Configuration.

Declares a Characteristic Extended Properties.

Declares a Characteristic User Format.

Each attribute contain a uuid, which describes their type, a read callback, a write callback and a set of permission. Both read and write callbacks can be set to NULL if the attribute permission don鈥檛 allow their respective operations.

Note

Attribute read and write callbacks are called directly from RX Thread thus it is not recommended to block for long periods of time in them.

Attribute value changes can be notified using bt_gatt_notify() API, alternatively there is bt_gatt_notify_cb() where is is possible to pass a callback to be called when it is necessary to know the exact instant when the data has been transmitted over the air. Indications are supported by bt_gatt_indicate() API.

Client procedures can be enabled with the configuration option: CONFIG_BT_GATT_CLIENT

Discover procedures can be initiated with the use of bt_gatt_discover() API which takes the bt_gatt_discover_params struct which describes the type of discovery. The parameters also serves as a filter when setting the uuid field only attributes which matches will be discovered, in contrast setting it to NULL allows all attributes to be discovered.

Note

Caching discovered attributes is not supported.

Read procedures are supported by bt_gatt_read() API which takes the bt_gatt_read_params struct as parameters. In the parameters one or more attributes can be set, though setting multiple handles requires the option: CONFIG_BT_GATT_READ_MULTIPLE

Write procedures are supported by bt_gatt_write() API and takes bt_gatt_write_params struct as parameters. In case the write operation don鈥檛 require a response bt_gatt_write_without_response() or bt_gatt_write_without_response_cb() APIs can be used, with the later working similarly to bt_gatt_notify_cb.

Subscriptions to notification and indication can be initiated with use of :cpp:func`bt_gatt_subscribe` API which takes bt_gatt_subscribe_params as parameters. Multiple subscriptions to the same attribute are supported so there could be multiple notify callback being triggered for the same attribute. Subscriptions can be removed with use of bt_gatt_unsubscribe() API.

Note

When subscriptions are removed notify callback is called with the data set to NULL.

Generic Attribute Profile (GATT)

Defines

Construct error return value for attribute read and write callbacks.

Appropriate error code for the attribute callbacks.

_att_err: ATT error code

Characteristic broadcast property.

If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor.

Characteristic read property.

If set, permits reads of the Characteristic Value.

Characteristic write without response property.

If set, permits write of the Characteristic Value without response.

Characteristic write with response property.

If set, permits write of the Characteristic Value with response.

Characteristic notify property.

If set, permits notifications of a Characteristic Value without acknowledgment.

Characteristic indicate property.

If set, permits indications of a Characteristic Value with acknowledgment.

Characteristic Authenticated Signed Writes property.

If set, permits signed writes to the Characteristic Value.

Characteristic Extended Properties property.

If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.

Client Characteristic Configuration Notification.

If set, changes to Characteristic Value shall be notified.

Client Characteristic Configuration Indication.

If set, changes to Characteristic Value shall be indicated.

Enums

Values:

No operations supported, e.g. for notify-only

Attribute read permission.

Attribute write permission.

Attribute read permission with encryption.

Attribute write permission with encryption.

Attribute read permission with authentication.

Attribute write permission with authentication.

Attribute prepare write permission.

Values:

Attribute prepare write flag

Attribute write command flag

GATT Attribute structure.

GATT Service structure.

GATT Service structure.

Service Attribute Value.

Include Attribute Value.

Characteristic Attribute Value.

Characteristic Extended Properties Attribute Value.

GATT Characteristic Presentation Format Attribute Value.

Defines

Statically define and register a service.

Helper macro to statically define and register a service.

_name: Service name.

Service Structure Declaration Macro.

Helper macro to declare a service structure.

_attrs: Service attributes.

Primary Service Declaration Macro.

Helper macro to declare a primary service attribute.

_service: Service attribute value.

Secondary Service Declaration Macro.

Helper macro to declare a secondary service attribute.

_service: Service attribute value.

Include Service Declaration Macro.

Helper macro to declare database internal include service attribute.

_service_incl: the first service attribute of service to include

Characteristic and Value Declaration Macro.

Helper macro to declare a characteristic attribute along with its attribute value.

_uuid: Characteristic attribute uuid.

_props: Characteristic attribute properties.

_perm: Characteristic Attribute access permissions.

_read: Characteristic Attribute read callback.

_write: Characteristic Attribute write callback.

_value: Characteristic Attribute value.

Initialize Client Characteristic Configuration Declaration Macro.

Helper macro to initialize a Managed CCC attribute value.

_changed: Configuration changed callback.

_write: Configuration write callback.

_match: Configuration match callback.

Managed Client Characteristic Configuration Declaration Macro.

Helper macro to declare a Managed CCC attribute.

_ccc: CCC attribute user data, shall point to a _bt_gatt_ccc.

_perm: CCC access permissions.

Client Characteristic Configuration Declaration Macro.

Helper macro to declare a CCC attribute.

_changed: Configuration changed callback.

_perm: CCC access permissions.

Characteristic Extended Properties Declaration Macro.

Helper macro to declare a CEP attribute.

_value: Descriptor attribute value.

Characteristic User Format Descriptor Declaration Macro.

Helper macro to declare a CUD attribute.

_value: User description NULL-terminated C string.

_perm: Descriptor attribute access permissions.

Characteristic Presentation Format Descriptor Declaration Macro.

Helper macro to declare a CPF attribute.

_value: Descriptor attribute value.

Descriptor Declaration Macro.

Helper macro to declare a descriptor attribute.

_uuid: Descriptor attribute uuid.

_perm: Descriptor attribute access permissions.

_read: Descriptor attribute read callback.

_write: Descriptor attribute write callback.

_value: Descriptor attribute value.

Attribute Declaration Macro.

Helper macro to declare an attribute.

_uuid: Attribute uuid.

_perm: Attribute access permissions.

_read: Attribute read callback.

_write: Attribute write callback.

_value: Attribute value.

Typedefs

Attribute iterator callback.

BT_GATT_ITER_CONTINUE if should continue to the next attribute or BT_GATT_ITER_STOP to stop.

attr: Attribute found.

user_data: Data given.

Notification complete result callback.

conn: Connection object.

Indication complete result callback.

0 in case of success or negative value in case of error.

conn: Connection object.

attr: Attribute object.

err: ATT error code

Enums

Values:

Functions

Register GATT service.

Register GATT service. Applications can make use of macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC, BT_GATT_DESCRIPTOR, etc.

0 in case of success or negative value in case of error.

svc: Service containing the available attributes

Unregister GATT service. *.

0 in case of success or negative value in case of error.

svc: Service to be unregistered.

Attribute iterator by type.

Iterate attributes in the given range matching given UUID and/or data.

start_handle: Start handle.

end_handle: End handle.

uuid: UUID to match, passing NULL skips UUID matching.

attr_data: Attribute data to match, passing NULL skips data matching.

num_matches: Number matches, passing 0 makes it unlimited.

func: Callback function.

user_data: Data to pass to the callback.

Attribute iterator.

Iterate attributes in the given range.

start_handle: Start handle.

end_handle: End handle.

func: Callback function.

user_data: Data to pass to the callback.

Iterate to the next attribute.

Iterate to the next attribute following a given attribute.

The next attribute or NULL if it cannot be found.

attr: Current Attribute.

Get the handle of the characteristic value descriptor.

the handle of the corresponding Characteristic Value. The value will be zero (the invalid handle) if attr was not a characteristic attribute.

attr: A Characteristic Attribute

Generic Read Attribute value helper.

Read attribute value from local database storing the result into buffer.

int number of bytes read in case of success or negative values in case of error.

conn: Connection object.

attr: Attribute to read.

buf: Buffer to store the value.

buf_len: Buffer length.

offset: Start offset.

value: Attribute value.

value_len: Length of the attribute value.

Read Service Attribute helper.

Read service attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_uuid.

int number of bytes read in case of success or negative values in case of error.

conn: Connection object.

attr: Attribute to read.

buf: Buffer to store the value read.

len: Buffer length.

offset: Start offset.

Read Include Attribute helper.

Read include service attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_gatt_include.

int number of bytes read in case of success or negative values in case of error.

conn: Connection object.

attr: Attribute to read.

buf: Buffer to store the value read.

len: Buffer length.

offset: Start offset.

Read Characteristic Attribute helper.

Read characteristic attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_gatt_chrc.

number of bytes read in case of success or negative values in case of error.

conn: Connection object.

attr: Attribute to read.

buf: Buffer to store the value read.

len: Buffer length.

offset: Start offset.

Read Client Characteristic Configuration Attribute helper.

Read CCC attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc.

number of bytes read in case of success or negative values in case of error.

conn: Connection object.

attr: Attribute to read.

buf: Buffer to store the value read.

len: Buffer length.

offset: Start offset.

Write Client Characteristic Configuration Attribute helper.

Write value in the buffer into CCC attribute. NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc.

number of bytes written in case of success or negative values in case of error.

conn: Connection object.

attr: Attribute to read.

buf: Buffer to store the value read.

len: Buffer length.

offset: Start offset.

flags: Write flags.

Read Characteristic Extended Properties Attribute helper.

Read CEP attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_gatt_cep.

number of bytes read in case of success or negative values in case of error.

conn: Connection object

attr: Attribute to read

buf: Buffer to store the value read

len: Buffer length

offset: Start offset

Read Characteristic User Description Descriptor Attribute helper.

Read CUD attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a NULL-terminated C string.

number of bytes read in case of success or negative values in case of error.

conn: Connection object

attr: Attribute to read

buf: Buffer to store the value read

len: Buffer length

offset: Start offset

Read Characteristic Presentation format Descriptor Attribute helper.

Read CPF attribute value from local database storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_gatt_pf.

number of bytes read in case of success or negative values in case of error.

conn: Connection object

attr: Attribute to read

buf: Buffer to store the value read

len: Buffer length

offset: Start offset

Notify attribute value change.

This function works in the same way as bt_gatt_notify. With the addition that after sending the notification the callback function will be called.

The callback is run from System Workqueue context.

Alternatively it is possible to notify by UUID by setting it on the parameters, when using this method the attribute given is used as the start range when looking up for possible matches.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Notification parameters.

Notify attribute value change.

Send notification of attribute value change, if connection is NULL notify all peer that have notification enabled via CCC otherwise do a direct notification only the given connection.

The attribute object on the parameters can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC.

0 in case of success or negative value in case of error.

conn: Connection object.

attr: Characteristic or Characteristic Value attribute.

data: Pointer to Attribute data.

len: Attribute value length.

Indicate attribute value change.

Send an indication of attribute value change. if connection is NULL indicate all peer that have notification enabled via CCC otherwise do a direct indication only the given connection.

The attribute object on the parameters can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC.

The callback is run from System Workqueue context.

Alternatively it is possible to indicate by UUID by setting it on the parameters, when using this method the attribute given is used as the start range when looking up for possible matches.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Indicate parameters.

Check if connection have subscribed to attribute.

Check if connection has subscribed to attribute value change.

The attribute object can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC, or the Client Characteristic Configuration Descriptor (CCCD) which is created by BT_GATT_CCC.

true if the attribute object has been subscribed.

conn: Connection object.

attr: Attribute object.

ccc_value: The subscription type, either notifications or indications.

Get ATT MTU for a connection.

Get negotiated ATT connection MTU, note that this does not equal the largest amount of attribute data that can be transferred within a single packet.

MTU in bytes

conn: Connection object.

GATT CCC configuration entry.

id: Local identity, BT_ID_DEFAULT in most cases.

peer: Remote peer address

value: Configuration value.

data: Configuration pointer data.

GATT Indicate Value parameters.

Typedefs

Discover attribute callback function.

If discovery procedure has completed this callback will be called with attr set to NULL. This will not happen if procedure was stopped by returning BT_GATT_ITER_STOP. The attribute is read-only and cannot be cached without copying its contents.

conn: Connection object.

attr: Attribute found.

params: Discovery parameters given.

BT_GATT_ITER_CONTINUE if should continue attribute discovery or BT_GATT_ITER_STOP to stop discovery procedure.

Read callback function.

conn: Connection object.

err: ATT error code.

params: Read parameters used.

data: Attribute value data. NULL means read has completed.

length: Attribute value length.

Write callback function.

conn: Connection object.

err: ATT error code.

params: Write parameters used.

Notification callback function.

conn: Connection object. May be NULL, indicating that the peer is being unpaired

params: Subscription parameters.

data: Attribute value data. If NULL then subscription was removed.

length: Attribute value length.

Enums

Values:

Discover Primary Services.

Discover Secondary Services.

Discover Included Services.

Discover Characteristic Values.

Discover Descriptors.

Discover Attributes.

Values:

Persistence flag

Write pending flag

Functions

Exchange MTU.

This client procedure can be used to set the MTU to the maximum possible size the buffers can hold.

NOTE: Shall only be used once per connection.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Exchange MTU parameters.

GATT Discover function.

This procedure is used by a client to discover attributes on a server.

Primary Service Discovery: Procedure allows to discover specific Primary Service based on UUID. Include Service Discovery: Procedure allows to discover all Include Services within specified range. Characteristic Discovery: Procedure allows to discover all characteristics within specified handle range as well as discover characteristics with specified UUID. Descriptors Discovery: Procedure allows to discover all characteristic descriptors within specified range.

For each attribute found the callback is called which can then decide whether to continue discovering or stop.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Discover parameters.

Read Attribute Value by handle.

This procedure read the attribute value and return it to the callback.

When reading attributes by UUID the callback can be called multiple times depending on how many instances of given the UUID exists with the start_handle being updated for each instance.

If an instance does contain a long value which cannot be read entirely the caller will need to read the remaining data separately using the handle and offset.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Read parameters.

Write Attribute Value by handle.

This procedure write the attribute value and return the result in the callback.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Write parameters.

Write Attribute Value by handle without response with callback.

This function works in the same way as bt_gatt_write_without_response. With the addition that after sending the write the callback function will be called.

The callback is run from System Workqueue context.

Note: By using a callback it also disable the internal flow control which would prevent sending multiple commands without waiting for their transmissions to complete, so if that is required the caller shall not submit more data until the callback is called.

0 in case of success or negative value in case of error.

conn: Connection object.

handle: Attribute handle.

data: Data to be written.

length: Data length.

sign: Whether to sign data

func: Transmission complete callback.

user_data: User data to be passed back to callback.

Write Attribute Value by handle without response.

This procedure write the attribute value without requiring an acknowledgment that the write was successfully performed

0 in case of success or negative value in case of error.

conn: Connection object.

handle: Attribute handle.

data: Data to be written.

length: Data length.

sign: Whether to sign data

Subscribe Attribute Value Notification.

This procedure subscribe to value notification using the Client Characteristic Configuration handle. If notification received subscribe value callback is called to return notified value. One may then decide whether to unsubscribe directly from this callback. Notification callback with NULL data will not be called if subscription was removed by this method.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Subscribe parameters.

Unsubscribe Attribute Value Notification.

This procedure unsubscribe to value notification using the Client Characteristic Configuration handle. Notification callback with NULL data will be called if subscription was removed by this call, until then the parameters cannot be reused.

0 in case of success or negative value in case of error.

conn: Connection object.

params: Subscribe parameters.

Cancel GATT pending request.

conn: Connection object.

params: Requested params address.

GATT Exchange MTU parameters.

GATT Discover Attributes parameters.

GATT Read parameters.

func: Read attribute callback

handle_count: If equals to 1 single.handle and single.offset are used. If >1 Read Multiple Characteristic Values is performed and handles are used. If equals to 0 by_uuid is used for Read Using Characteristic UUID.

handle: Attribute handle

offset: Attribute data offset

handles: Handles to read in Read Multiple Characteristic Values

start_handle: First requested handle number

end_handle: Last requested handle number

uuid: 2 or 16 octet UUID

GATT Write parameters.

GATT Subscribe parameters.